结构归纳引擎 V13
命令速查 文件速查

7884 结构归纳引擎使用文档

引擎版本: V13 | 最后更新: 2026-07-02 | 实测环境: Windows 11, RTX 5090 24G, 20核CPU

目录

  • 引擎概述
  • 环境准备
  • 5 分钟快速上手
  • 命令行参数详解
  • 三种运行模式
  • 输出文件解读
  • Gen 模式使用指南
  • Python 插件开发
  • 质量指标怎么看
  • 故障排除
  • 最佳实践

    • 1. 引擎概述

    1.1 这东西能帮我做什么？

    7884 结构归纳引擎是一个 二进制格式分析工具。你给它几个同类型的文件（比如几个 BMP 图片），它能自动分析出这些文件的结构，并帮你做以下事情：

    场景具体用途
    逆向未知格式拿到一个不知道结构的二进制文件，让引擎帮你分析出字段、偏移、类型
    生成结构描述自动生成 Python 校验脚本、010 Editor 模板、YARA 规则等
    批量变异测试基于分析结果，自动生成大量变异样本用于模糊测试
    格式校验使用生成的 Python 脚本验证文件是否合法

    一句话总结：给样本 → 出结构 → 测变异。

    1.2 核心功能

  • 结构归纳：自动分析二进制文件中的字段、偏移、类型、关系
  • 多格式输出：同时生成 Python / BT / Kaitai / Peach XML / YARA / C / Lua 等格式
  • 变异测试：支持 Basic（15种策略）和 Pro（46种策略）两种引擎
  • CUDA 加速：利用 GPU 加速 ML 推理和 CRC 校验验证
  • 容器穿透：自动解包 ZIP/GZIP/TAR 容器文件

    • 1.3 适用人群

    角色能用它做什么
    安全研究员逆向分析未知二进制格式，生成 Fuzzing 样本
    逆向工程师快速理解文件结构，获得 010 Editor 模板
    漏洞挖掘工程师使用 Gen 模式批量生成变异样本

    1.4 与传统工具的关系

    工具你的工作7884 能帮你
    010 Editor手动分析二进制自动生成 .bt 模板
    Kaitai Struct声明式格式定义自动生成 .ksy 文件
    YARA恶意样本匹配自动生成 .yar 规则
    AFL++覆盖引导模糊测试自动生成 .dict 字典

    2. 环境准备

    2.1 你需要什么

    项目最低要求推荐
    操作系统Windows 10 x64Windows 11 x64
    内存4 GB8 GB+
    CPU4 核8 核+
    GPU（可选）—NVIDIA GPU，支持 CUDA
    Python（可选）Python 3.8+运行配套脚本用

    2.2 文件清单

    文件说明
    7884_brain.exe引擎主程序，包含全部功能
    IFFA.exe辅助分析模块（由主程序自动调用）

    2.3 ⚠️ 重要限制

    IFFA.exe 使用时有以下限制（从 V13 实测发现）：

  • 路径不能包含空格（如 C:\My Samples\ 不行）
  • 路径不能包含中文
  • 需要至少 3 个样本文件才能触发 IFFA 分析

    • 2.4 推荐目录结构

    ${WORKSPACE}/
├── 7884_brain.exe          # 引擎主程序
├── IFFA.exe                # 辅助模块
├── test_samples/           # 存放样本
│   └── bmp/
│       ├── sample_100x100.bmp
│       ├── sample_200x150.bmp
│       └── sample_50x80.bmp
├── output/                 # 分析结果会输出到这里
├── scripts/                # 配套 Python 脚本
└── docs/                   # 文档

    2.5 验证安装

    cd ${WORKSPACE}
.\7884_brain.exe

    预期输出：显示引擎 Banner 和帮助信息。如果没有报错，说明引擎正常工作。

      =================================================================
  |                      7 8 8 4                                  |
  |   Structure Induction Engine V13 by 20260628                  |
  =================================================================
  |   CPU Cores: 20      Memory: 32684  MB                       |
  |   CUDA: Available     GPU Memory: 24 GB                      |
  =================================================================
    注意：引擎默认精简输出，正常运行时控制台只显示关键信息，详细日志写入文件。

    3. 5 分钟快速上手

    本章用一个 BMP 文件分析流程，带你跑通全链路。跟着做就行，不用理解原理。

    Step 1：准备样本

    把待分析的二进制文件放到一个目录下：

    # 确认样本存在（3 个不同尺寸的 BMP 文件）
dir ${WORKSPACE}\test_samples\bmp

    预期输出：

    sample_100x100.bmp     sample_200x150.bmp     sample_50x80.bmp
    样本要求：至少 1 个，推荐 3-5 个同格式文件。文本文件（.txt/.md）会被自动跳过。

    Step 2：运行结构归纳

    cd ${WORKSPACE}
.\7884_brain.exe --input test_samples/bmp --output output

    预期输出：Banner 信息 + 分析进度。结束后退出码为 0。

    如果报错：

  • CUDA manager 错误 → 你的 GPU 不支持 CUDA，改用 --cuda-disable
  • Directory is empty → 样本目录里没有二进制文件
  • 路径含空格报错 → 把样本移到不含空格的路径下

    • 引擎完成后，在 output/ 下生成一个时间戳目录，例如 output_20260702_201821/。

    实测数据（RTX 5090, 3个BMP样本）：

    指标值
    总耗时~62.8 秒
    其中 IFFA 分析~45.9 秒（最耗时模块）
    发现字段数257
    发现关系数1304
    总体质量评分0.78

    Step 3：查看结果

    打开生成的 HTML 报告：

    start output/output_20260702_201821/structure_report.html

    或者用配套脚本解析 JSON：

    python scripts/03_output_reader.py --input output/output_20260702_201821/structure_report.json

    输出示例：

    =================================================================
  字段结构树（共 257 个字段）
=================================================================
  ├─ [  0] Magic_0x424D6675    类型: DWORD  偏移: 0  大小: 4
  ├─ [  1] NullData_6_bytes    类型: WORD   偏移: 4  大小: 6
  ...
─────────────────────────────────────────────────────────────────
  质量评分
─────────────────────────────────────────────────────────────────
    quality_overall: 0.78    coverage: 1.0
    consistency: 0.822       refutation: 0.4695

    Step 4：生成变异样本

    基于生成的 Peach XML 配置，生成 10 个变异样本：

    .\7884_brain.exe --Gen output/output_20260702_201821/example/format_schema.xml -i 10

    预期输出：

    [*] Starting fuzzing, iterations 1-10
[*] Engine: Basic (default)
[*] Fuzzing completed. Generated 10 samples
    遇到问题？ Error: Failed to load XML → 确认 XML 文件路径正确。

    Step 5：验证变异样本

    # 列出生成的变异文件
dir ${WORKSPACE}\OutSample\*.bmp

    到此完成！你已经跑通了 样本 → 分析 → 结果查看 → 变异生成 的完整流程。

    4. 命令行参数详解

    4.1 结构归纳模式

    对样本执行结构分析，输出结构描述文件。

    基本语法：

    7884_brain.exe --input <样本目录> --output <输出目录> [可选参数]

    参数列表：

    参数说明默认值
    --input <dir> / -i输入样本目录（必填）—
    --output <dir> / -o输出目录./output
    --cuda-enable启用 CUDA 加速自动检测
    --cuda-disable禁用 CUDA—
    --batch <num>批处理大小128
    --cpu-threads <num>CPU 线程数8
    --max-iterations <num>最大训练迭代次数100
    --plugin-dir <dir>Python 插件目录无
    --log <file>日志文件路径./logs/run_log.txt

    实际可用命令：

    # 完整模式（自动检测 CUDA）
7884_brain.exe --input test_samples/bmp --output output

# 无 GPU 时禁用 CUDA
7884_brain.exe --input test_samples/bmp --output output --cuda-disable

# 轻量模式（快速预览）
7884_brain.exe --input test_samples/bmp --output output --cuda-disable --max-iterations 50 --cpu-threads 4

# 指定插件目录
7884_brain.exe --input test_samples/bmp --output output --plugin-dir my_plugins

    4.2 Gen 模式（变异样本生成）

    基于生成的 Peach XML 配置，批量生成变异样本。

    基本语法：

    7884_brain.exe --Gen <xml_file> [-i N] [-o PATH] [-s SEED] [--engine basic|pro]

    参数列表：

    参数说明默认值
    --Gen <xml_file>启动 Gen 模式（必填）—
    -i, --iterations <N>迭代次数1000
    -o, --output <path>输出路径模板fuzz_{0}.bin
    -s, --seed <N>随机种子（相同种子可复现）当前时间
    --engine basic/pro变异引擎选择basic
    --range N,M断点续跑—
    -1单次迭代（等价于 -i 1）—

    实际可用命令：

    # 基本用法（Basic 引擎，1000 次迭代）
7884_brain.exe --Gen output/xxx/example/format_schema.xml

# 指定迭代次数和输出路径
7884_brain.exe --Gen output/xxx/example/format_schema.xml -i 100 -o "fuzz\{0}.bin"

# Pro 引擎 + 指定种子（可复现）
7884_brain.exe --Gen output/xxx/example/format_schema.xml --engine pro -i 500 -s 42

# 断点续跑（从第 10 次跑到第 20 次）
7884_brain.exe --Gen output/xxx/example/format_schema.xml --range 10,20

# 单次变异快速测试
7884_brain.exe --Gen output/xxx/example/format_schema.xml -1

    4.3 退出码说明

    退出码含义怎么办
    0成功去输出目录看结果
    1失败看控制台错误信息，参考第 10 章故障排除

    5. 三种运行模式

    引擎通过组合参数实现不同的运行模式。注意：引擎没有 --mode 参数，你需要手动组合以下参数。

    5.1 完整模式（默认，有 GPU 时用）

    7884_brain.exe --input test_samples/bmp --output output
  • 自动检测 CUDA，有 GPU 就用
  • 完整管线：IFFA + GPU ML 推理 + CRC 校验
  • 适合场景：正式分析，追求最佳结果

    • 5.2 仅 CPU 模式（无 GPU 时用）

    7884_brain.exe --input test_samples/bmp --output output --cuda-disable
  • 禁用 GPU，所有计算在 CPU 上执行
  • 完整管线，只是慢一些
  • 适合场景：无 GPU 环境、虚拟机、CI/CD 自动化

    • 5.3 轻量模式（快速预览）

    7884_brain.exe --input test_samples/bmp --output output --cuda-disable --max-iterations 50 --cpu-threads 4
  • 跳过 GPU 推理，降低迭代次数
  • 输出文件完整，但分析深度较浅
  • 适合场景：快速验证样本是否有效、初次体验

    • 5.4 实测对比

    模式总耗时IFFA 耗时说明
    完整~62.8 秒~45.9 秒完整管线，GPU 推理
    仅 CPU更慢~45.9 秒ML 推理在 CPU 执行
    轻量~60 秒~45.9 秒跳过 GPU 推理
    关键结论：IFFA 是最耗时的模块，约占 73%。无论哪种模式，IFFA 都会执行。轻量模式主要跳过 GPU 推理阶段。

    5.5 我用哪个？

    有 NVIDIA GPU 吗？
├── 是 → 想完整分析？→ 默认模式（不加 --cuda-disable）
│       想快速看看？→ 轻量模式
└── 否 → 想完整分析？→ 加 --cuda-disable
        想快速看看？→ 轻量模式

    6. 输出文件解读

    引擎在 --output 目录下生成 output_YYYYMMDD_HHMMSS/ 时间戳子目录，里面包含以下文件。

    6.1 我想看分析结果 → structure_report.html

    浏览器打开，可视化展示所有分析结果。推荐从此入手。

    start output/output_20260702_201821/structure_report.html

    6.2 我想在代码里读取结果 → structure_report.json

    JSON 格式，包含所有字段、关系、质量指标。用配套脚本解析：

    python scripts/03_output_reader.py --input output/output_20260702_201821/structure_report.json

    质量评分示例（实测数据）：

    {
  "quality": {
    "quality_overall": 0.78,
    "coverage": 1.0,
    "consistency": 0.822,
    "refutation": 0.4695,
    "cross_validation": 0.9999
  }
}

    6.3 我想校验文件 → example/format_schema.py

    可直接运行的 Python 校验脚本：

    python output/output_20260702_201821/example/format_schema.py sample.bmp

    输出示例：

    文件格式: 已识别且验证通过

    6.4 我想生成变异样本 → example/format_schema.xml

    Peach XML 格式的配置，传给 --Gen 参数使用。

    6.5 我想在 010 Editor 里看结构 → example/format_schema.bt

    010 Editor → Templates → Open Template → 选择此文件。

    6.6 我想写一个解析器 → example/format_schema.ksy

    Kaitai Struct 格式，可编译为 Python/Java/C++ 等语言：

    kaitai-struct-compiler format_schema.ksy -t python

    6.7 我想检测恶意样本 → example/format_schema.yar

    YARA 规则：

    yara format_schema.yar sample.bmp

    6.8 其他文件

    文件名用途
    iffa_structure_analysis.txtIFFA 详细逆向报告
    performance.csv各模块耗时统计（怀疑引擎慢时看这个）
    sampling_suggestions.txt覆盖度分析和增量采样建议
    test_suite.txt边界测试用例（154 个）
    test_results.txt边界测试执行结果
    afl_dictionary.dictAFL 字典（92 条词条）
    trained_model.model训练好的 ML 模型
    structure_diff.html样本间结构差异对比

    7. Gen 模式使用指南

    7.1 基本用法

    前置条件：先运行结构归纳，获得 format_schema.xml 文件。

    # Step 1：结构归纳
7884_brain.exe --input test_samples/bmp --output output

# Step 2：找到 XML 文件（在 output/output_YYYYMMDD_HHMMSS/example/format_schema.xml）

# Step 3：运行 Gen 模式
7884_brain.exe --Gen output/xxx/example/format_schema.xml -i 100

    7.2 Basic vs Pro 引擎

    对比Basic（默认）Pro（--engine pro）
    变异策略数15 种46 种
    策略覆盖率15.2%（实测）41.3%（实测）
    总变异操作11（实测）37（实测）
    Havoc 组合无8~32 层叠加
    确定性遍历无7 阶段
    字典注入无✅
    整数溢出无✅
    运行速度快（0.03秒/10次）较慢
    推荐迭代次数100~10,0001,000~100,000

    选哪个？

  • 只是想快速生成一些样本 → Basic
  • 追求触发更多异常 → Pro
  • 不确定 → 先用 Basic 试，效果好就不用换

    • 7.3 种子复现

    # 第一次运行（指定种子）
7884_brain.exe --Gen format_schema.xml -i 100 -s 42

# 第二次运行（相同种子，得到完全相同的结果）
7884_brain.exe --Gen format_schema.xml -i 100 -s 42
    用于 Bug 复现和回归测试。不指定 -s 则每次结果不同。

    7.4 断点续跑

    # 计划跑 10000 次，跑到 5000 次时中断了
# 从中断处继续，跑 5001~10000 次
7884_brain.exe --Gen format_schema.xml --range 5001,10000

    8. Python 插件开发

    引擎支持三种类型的 Python 插件，让你在分析管线的不同阶段注入自定义逻辑。

    8.1 插件类型

    类型执行阶段用途
    analyzer分析阶段自定义分析逻辑
    output输出阶段自定义输出格式
    post_processor后处理阶段结果过滤、统计、报表

    8.2 插件基础接口

    class PluginBase:
    plugin_info = {
        "name": "my_plugin",
        "version": "1.0.0",
        "description": "My custom plugin",
        "plugin_type": "output",
        "author": "Me",
    }

    def run(self, context):
        # context 包含 input_path, results, config
        return {"success": True, "message": "ok", "data": {}}

    完整示例见 scripts/07_plugin_example.py。

    8.3 加载插件

    7884_brain.exe --input test_samples/bmp --output output --plugin-dir my_plugins/

    插件加载顺序：analyzer → output → post_processor。

    9. 质量指标怎么看

    每个指标范围 0.0~1.0，越高越好。

    指标实测值可接受含义怎么提升
    quality_overall0.78≥ 0.70综合质量评分增加样本数量
    coverage1.0≥ 0.80已识别字段占总字节比例增加样本多样性
    consistency0.822≥ 0.70跨样本字段一致性确保样本同格式
    refutation0.4695≥ 0.50结构假设被验证的程度增加样本数量
    cross_validation0.9999≥ 0.85不同分析路径的交叉验证使用更多样本

    简单判断：

  • overall ≥ 0.70：结果可用，有参考价值
  • overall ≥ 0.85：结果可靠，可以直接用
  • refutation < 0.50：样本太少，加几个样本

    • 10. 故障排除

    10.1 常见错误

    错误信息原因解决方法
    Error: Failed to load samples from directory样本目录不存在或为空确认目录存在且包含二进制文件
    Directory is empty or contains no readable files目录中没有有效二进制文件放入 .bmp/.png/.zip 等文件
    Error: Failed to create CUDA managerGPU 不可用加 --cuda-disable
    Error: Failed to create sample analyzer内存不足检查可用内存（≥ 4GB）
    退出码 1 + 无错误信息输入目录无有效文件确认目录中有非文本二进制文件
    Gen 模式找不到 XML路径错误先运行结构归纳生成 XML
    IFFA 报错路径含空格或中文移到不含空格/中文的路径
    控制台没有输出V13 默认精简输出看日志文件，这是正常现象

    10.2 常见场景

    CUDA 不可用

    7884_brain.exe --input samples --output output --cuda-disable

    空目录报错

    # 检查目录内容
dir test_samples/bmp
# 确保有 .bmp 等二进制文件

    IFFA 耗时过长

    IFFA 占 73% 的总时间（约 46 秒），这是正常的。如果觉得慢：

  • 确认样本数量合适（3~5 个）
  • 轻量模式不会跳过 IFFA

    • 输出目录找不到

    引擎在 --output 目录下创建时间戳子目录。用配套脚本自动定位：

    python scripts/01_run_induction.py --input test_samples/bmp --mode lightweight

    10.3 常见问题 Q&A

    Q: 引擎运行后控制台没输出，是不是坏了？

    A: 不是。V13 版本默认精简输出，只显示关键信息和错误。所有详细信息写入日志文件。

    Q: 为什么 lightweight 模式也要跑 60 秒？

    A: lightweight 模式跳过的是 GPU 推理，但 IFFA 模块（~46 秒）仍然会执行。

    Q: 样本放哪个目录？

    A: 任意目录，只要路径不含空格和中文。推荐用纯英文路径。

    Q: 能分析哪些格式？

    A: 任意二进制格式（BMP, PNG, ZIP, PE, ELF 等）。文本文件（.txt/.md）会被自动跳过。

    Q: 需要几个样本？

    A: 最少 1 个，推荐 3~5 个。太少则质量评分偏低。

    Q: 输出文件在哪里？

    A: 在 --output 目录下的 output_YYYYMMDD_HHMMSS/ 子目录中。

    Q: 生成的 Python 脚本怎么用？

    A: python format_schema.py <要校验的文件>

    Q: --mode 参数怎么不能用？

    A: 引擎没有 --mode 参数。参考第 5 章，用 --cuda-disable 等参数组合实现。

    11. 最佳实践

    11.1 样本准备

  • 数量：推荐 3~5 个同格式样本
  • 多样性：选择不同大小、不同内容的样本
  • 存放：每个格式单独一个目录
  • 路径：不要含空格和中文

    • 11.2 模式选择

    场景推荐配置
    第一次用，想试试--cuda-disable --max-iterations 50 --cpu-threads 4
    正式分析，有 GPU默认参数
    正式分析，无 GPU--cuda-disable
    批量分析先用轻量筛选，再正式分析

    11.3 Gen 模式迭代次数

    目的迭代次数引擎
    快速测试10~100Basic
    一般 Fuzzing1,000~10,000Basic
    深度 Fuzzing10,000~100,000Pro

    11.4 配套脚本推荐

    # 结构归纳（自动定位输出目录）
python scripts/01_run_induction.py --input test_samples/bmp --output output

# 生成变异样本
python scripts/02_run_gen.py --xml output/xxx/example/format_schema.xml -i 1000

# 解析结果
python scripts/03_output_reader.py --input output/xxx/structure_report.json

    11.5 完整工作流

    # 1. 验证样本
dir ${WORKSPACE}\test_samples\bmp\

# 2. 轻量分析（快速预览）
7884_brain.exe --input test_samples/bmp --output output --cuda-disable --max-iterations 50 --cpu-threads 4

# 3. 查看质量评分
python scripts/03_output_reader.py --input output/latest/structure_report.json

# 4. 如果质量可接受，正式分析
7884_brain.exe --input test_samples/bmp --output output

# 5. 生成变异样本
7884_brain.exe --Gen output/latest/example/format_schema.xml -i 10000

# 6. 用变异样本测试你的解析器
    文档版本: v2.0 | 引擎版本: V13 | 最后更新: 2026-07-02

    >

    配套脚本在 scripts/ 目录，测试样本在 test_samples/ 目录。
    命令速查表见 docs/APPENDIX_A_cheatsheet.md，输出文件速查表见 docs/APPENDIX_B_output_reference.md。

    7884 结构归纳引擎使用文档 v2.0 | 引擎版本: V13 | 最后更新: 2026-07-02

    实测环境: Windows 11, RTX 5090 24G, 20核CPU, 32GB RAM